/*
 * // Bristleback plugin - Copyright (c) 2010 bristleback.googlecode.com
 * // ---------------------------------------------------------------------------
 * // This program is free software; you can redistribute it and/or modify it
 * // under the terms of the GNU Lesser General Public License as published by the
 * // Free Software Foundation; either version 3 of the License, or (at your
 * // option) any later version.
 * // This library is distributed in the hope that it will be useful,
 * // but without any warranty; without even the implied warranty of merchantability
 * // or fitness for a particular purpose.
 * // You should have received a copy of the GNU Lesser General Public License along
 * // with this program; if not, see <http://www.gnu.org/licenses/lgpl.html>.
 * // ---------------------------------------------------------------------------
 */

package pl.bristleback.server.bristle.token;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;

/**
 * Description of adding parameters to token operation. Marks {@link Tokenizer} fields.
 * Describes names of added parameters and optionally: tokenizer class, deep search of value fields and name of parameter set.
 * To have multiple {@link Tokenize} annotations above one tokenizer field, see {@link TokenizeSet} annotation.
 * <p/>
 * Created on: 2010-12-16 14:24:44 <br/>
 *
 * @author Wojciech Niemiec
 */
@Target({ElementType.FIELD})
@Retention(java.lang.annotation.RetentionPolicy.RUNTIME)
public @interface Tokenize {

  /**
   * Indicates whether deep search of value fields should be performed. Default <code>false</code>.
   *
   * @return true if deep search of value fields should be performed, false otherwise.
   */
  boolean deepSearch() default false;

  /**
   * Points what tokenizer engine implementation should be used to pass values to token.
   * Default {@link JsonTokenizerEngine} is used.
   *
   * @return object tokenizer implementation used to pass values to token.
   */
  Class<? extends TokenizerEngine> engine() default TokenizerEngine.class;

  /**
   * Names of parameters under which values will passed to token. <b>Required.</b>
   *
   * @return names of parameters.
   */
  String[] parameters();

  /**
   * Name of this parameter passing operation. Default value is empty.
   * If there are multiple {@link Tokenize} annotations with the same number of parameters,
   * they must provide unique name to identify them. To add named values (parameter <code><b>name</b></code> of this annotation is not empty),
   * invoke {@link Tokenizer#tokenizeNamed} method.
   *
   * @return name of this parameter passing operation
   */
  String name() default "";
}
